Almathera Ten Pack 2: CDPD 1

home *** CD-ROM | disk | FTP | other *** search

/ Almathera Ten Pack 2: CDPD 1 / Almathera Ten on Ten - Disc 2: CDPD 1.iso / pd / 076-100 / 087 / commodities / manual (.txt) < prev next >

Wrap

Microsoft Windows Help File Content | 1995-03-13 | 37KB | 678 lines

:bk=0 Commodities Exchange Reference Manual version 0.3, March 18, 1987 This manual and Commodities Exchange were written by Jim Mackraz. Copyright 1987, Jim Mackraz. No part of this manual or accompanying software may be sold for profit or included in any for-profit product without written authorization from the author. Free and at-cost distribution of this package is welcome. The source code for "commodities.library" is not to be compiled for any reason without written consent of the author. All users of the Commodities Exchange are urged to respect the standards put forth in the documentation. ----- PREFACE -------------------------------------------- This manual is the first draft of the programmer's reference to Commodities Exchange. It accompanies a release which might best be called "Alpha 2" but will be referred to as "Version 0.3." As the body of the manual describes, every attempt has been made to provide a complete system which will enable applications to be written in an upwardly compatible way. The end of this document contains sort of an Appendix on the major improvement of Version 0.3: InvertKeyMap() and the improvement to ParseIX(). Also, AddIEvents() is new. See also the function descriptions. More features and utilities will address new areas. The contents of a release are described in a file named README on the release disk. In addition to this document, required reading includes the collected function references, the application #include files, and the example applications provided. Familiarity with the input.device, in particular the contents of the include file devices/inputevent.h is necessary. Exec Lists, Messages and Message Ports play a fundamental role in the system, and must also be understood. The source for the scanned support library, cx_support.lib, is also educational. The author wishes to warmly thank Neil Katin for his indispensible aid and suggestions, and Andy Finkel for being a patient, yet constant encouragement to complete the project. Also, the team at Meridian Software have been very helpful and encouraging. The eventual distribution path for commodities.library has yet to be determined. The attempt at a copyright notice above is trying to express these intentions: -The library may be distributed in object form for free. -No one makes money off of this without written consent, which will be quite easily obtained. -I don't want the source to the library itself compiled; I want control over that. Any example application or scanned library function may be freely used for non-for- profit programs. -I hope people write programs which handle errors carefully, use the ToolTypes as described, and look real sharp. -Later versions of the library and controller may be shareware, but arrangements can be made with anyone wishing to use the library with a commercial product. Lastly, I want to encourage all feedback possible. In particular, I would be glad to recommend approaches to your envisioned applications, and will enhance the library to support needed features as I become aware of them. This manual is also undoubtedly lacking. Please forgive this first draft and feel welcome in giving advice for its revision. Please contact me by mail or in person: Jim Mackraz 7101 Rainbow Dr. #8 San Jose, CA 95129 ----- INTRODUCTION ------------------------------------- Commodities Exchange has as its major component an Amiga Exec Library, named "commodities.library." If this library is put in logical volume LIBS:, it can be opened and used by application programs to gain access to input in a very flexible way. In particular, an application of Commodities can monitor the Amiga input stream coming from the input.device without using an Intuition Window or a Console. This gives rise to the following motivational paragraphs. The Amiga computer provides a low-overhead, message-based multi-tasking operating environment, complete with a multi-threaded DOS and Graphics/Windows environment. No other PC provides this, yet the impact sometimes seems to be lost on the personal computing community at large. To some degree, this is explained by surrogate multi-tasking providing a high degree of satisfaction on popular competitors such as the Apple Macintosh and IBM PC. Small programs called Desk Accessories, Pop-Up programs, Resident programs, Terminate-and-Stay-Resident programs and the like provide multiple application capability, with some limits. Technical problems with the ad hoc methods of providing these functions on existing microcomputers find their way to the user, who must often empirically determine what programs may safely coexist, and in what order they must be "loaded." Most of the technical problems in writing such programs are non-existent on the Amiga. In particular, using disk operating system services in pop-up programs is a black art on an IBM PC. A principle area of difficulty or awkwardness is the monitoring of input, be it for the purpose of triggering a pop-up program, performing spelling checking as words are typed, or translating keystrokes into sequences. On the Amiga, the input problem is fundamentally solved by the input.device which provides an endorsed means of adding "input handlers." Unfortunately, without standards, arbitrary use of input handlers by uncooperative programs can quickly lead to incompatibilities or "load-order dependence" even on the Amiga. Furthermore, writing input handlers is far from trivial, especially using "small model" compilation as provided by Aztec C. Which brings us to the goal of the Commodities Exchange. Commodities consists of a single input handler which precedes the Intuition input handler. Like Intuition, Commodities will route input events to multiple applications. Commodities applications typically are interested in input regardless of what Window is active, and thus Commodities is used as a simple, standardized way of managing the input of a "Resident" type program. Taken with the standards described in this document for user-specification of the input which triggers an action, and for establishing the priority of individual Commodities applications, it is hoped that many high-quality, mutually co-existent "Resident" programs will be created by the amazing Amiga programming community. Next we describe the end-user's view of several Commodities applications. The source code for these is provided with the release. These programs together illustrate the most common principles of Commodities, and will serve as examples for the rest of this manual. ----- SOME EXAMPLES ------------------------------------ To run any of the following examples, the user must put a copy of the file "commodities.library" into his or her LIBS: directory, where it will be found when the program begins execution. All applications below would normally be started from the Workbench by opening (double-clicking) their icon. As we shall see, information in the icon is used to configure the programs. -- IHELP -- This application is just in its infancy, I swear. Its purpose is to provide keyboard control of Intuition window operations, to lessen (ultimately to eliminate) the need for using the mouse while doing keyboard intensive work, such as writing software or documents. This program was the prime motivation for the Commodities Exchange. It is the author's firm belief that managing a multi-tasking user interface is too important a task to assign exclusively to a low-bandwidth device such as a mouse. Currently, IHelp provides three functions: CYCLE -- this function causes the rearmost application window on the Workbench to be brought to the front and Activated. MAKESMALL -- the active window is shrunk to its minimum dimensions. MAKEBIG -- the active window is made the maximum size possible respecting its limits and the edge of the screen. Each of these functions is assigned to an input event, typically a keystroke such as a function key. Pressing the proper key causes the action to take place regardless of which window is active or what use the active window may be making of keyboard input. In order to allow the user the ability to associate keystrokes (or other events) with these actions, the ToolType fields in the program (Tool) icon are used. The user selects (but does not open) the icon for IHelp, and selects "Info" from the Workbench menu. The subsequent display allows the addition, editing, and deletion of parameter strings called ToolTypes. To assign the three functions above to new keystrokes, ToolType items are added or edited to read, for example: CYCLE=f1 MAKEBIG=alt f5 MAKESMALL=shift alt f5 The icon is saved, and the next time IHelp is loaded these keystrokes prescribed by the user will be associated with the program's actions. -- NOCAPSLOCK -- This application is almost invisible to the user. It monitors all keystrokes and insures that the CAPSLOCK key on the keyboard never has any effect (regardless of what its little red light says). The shift keys still function normally, but the frequent annoying effects of inadvertant pressing of the CAPSLOCK key are no more. This program provides nothing the user would want to change, so no ToolType fields in its icon are used. -- AUTOPOINT2 -- This function was inspired by Jude Katsch's Autopoint, which is a program to emulate SunWindows style window activation. Whenever the mouse is moved (without a button depressed) this program triese to activate the window under the mouse pointer if it is not already active. The tricky part of this program was to make it work with the Workbench Rename gadget, which it does nicely. Again, no ToolType fields are used. ----- COMMODITIES COMPONENTS ------------------------------- The Commodities Exchange consists of several identifiable components which we introduce now. -- commodities.library -- This is an Amiga Exec library which creates an input handler when it is initialized. It provides a large number of functions to manipulate Commodities Objects and Messages, the building blocks of a Commodities application. All access to data used by this library is done procedurally: no internal data structures are read or modified directly by application programs. The functions provided by the library fall into classes: -Object Creation/Deletion -Object Linking -Object Data Access/Modify -Object Type-specific Functions -Input Event Matching Utilities -Message Routing/Disposing The library must be opened (using the Exec function OpenLibrary()) by each Commodities application. All parameters to the library, following Amiga library convention, are thirty-two bit quantities. Small-integer users must remember that integers and characters are not promoted to thirty-two bits by the compiler, so casts must be used. In particular, don't forget to cast boolean and priority values to (LONG). -- Controller program -- An application program will be used to see the loaded Commodities and their functions. It will be possible to use this program to terminate an application. It is an unrealized design goal to write the controller using public information and interface functions so that it would be upwardly object compatible. In fact, the controller, if it exists at all, is very rudimentary at the present time. -- Support Scanned Library -- A "scanned" library is also provided. Its name is "cx_support.lib." A scanned library contains functions which are linked into the executable file of an application. Included are interface routines to commodities.library and some utility functions. The functions are all compatible with Aztec C conventions, and are compiled "small code, small data, small integer." -- Include Files -- Various include files are provided. For applications, the file "cxusr.h" contains the principle information and itself includes the other application include files. The file "cx.h," if you ever see it, contains library private data structures and constants which are not guaranteed to be compatible from release to release. They should not be used by any Commodities applications. Assembler versions of the include files don't exist yet. -- Source Examples -- As mentioned, the source for the programs IHelp, NoCapsLock, and AutoPoint2 is provided. -- Commodities Applications -- You write these. They open "commodities.library" and perhaps use functions in the scanned library. They create and interconnect objects (see below) in such a way that particular events cause desired actions or notifications. ----- COMMODITIES OVERVIEW ------------------------------- -- Objects and Messages -- The basic building block is the Commodities Exchange Object, or CxObj. Each object is of some particular 'type' which corresponds to the primitive action that occur when a Commodities Message arrives at the object. The objects are connected together in a large tree structure and messages corresponding to input events rattle down different paths in the tree, triggering different actions as they encounter different objects. One particular object type is the Custom object, which calls an application provided function when a CxMsg arrives, so that programmers can provide virtually any function not available with the standard CxObj types. A Commodities Exchange Message, or CxMsg, corresponds with few exceptions to a single Input Event. When such a message arrives at a CxObj, an action takes place. This action might be the sending of an Exec message to an application message port, the diversion of the CxMsg down a sub-tree, or the calling of an application-provided function. All objects can be disabled (inactivated), which inhibits any action being taken when a CxMsg arrives. The message simply proceeds along to its default next destination. Each CxObj is itself an Exec Node; one finds objects linked together in linear lists. Each object also contains a List Header, which we refer to as its "personal list," so branching off from any object can be another list. So although the entire linked structure of CxObj's is indeed a tree, there is a definite preferred--or default--direction at each node of the tree. Starting with a Master List of CxObj's, CxMsg's tend to visit every object in a list in turn, but certain objects can divert them "90 degrees" whence they head off down another list, normally the "personal list" of the CxObj performing the diversion. When (and if) the CxMsg reaches the end of a list, it proceeds from where it was diverted. A stack is maintained for each CxMsg to record and recover from multiple diversions. -- Brokers and Application Sub-Trees -- The CxObj's in the Master List are a special lot. They are called Commodities Brokers (get it?) and are typically in one-to-one correspondence with application programs. They are "representatives" of the application programs; the sub-tree starting with the personal list of a Broker consists of the CxObj's created by the application. When it is enabled, a Broker will divert ALL CxMsg's it receives down its personal list, into the network of objects the application has set up. Support is provided for preventing the creation of duplicate brokers. This gives the application an easy way of determining during its initialization if there is another copy of itself already running. The new copy can terminate, and it can be arranged that the existing copy be notified that a restart attempt was made. A resident but dormant pop-up notepad program might take such a notification that it should open up a window and swing into action. -- Standard Objects -- The actions performed by CxObj's of the standard types are intended to be primitive. An application wishing to receive an Exec message when a particular keystroke occurs must create three CxObj's for the task: one to filter the CxMsg's for one corresponding to the keystroke, and attached to its list, a CxObj to send off an Exec Message and another (optional) to swallow the CxMsg. These three are in addition to the application's (single) broker. A filter acts by diverting a select set of CxMsg's down its personal list, where they will encounter the other two objects who unconditionally perform their action. Here is a summary of the CxObj types and a brief description of each: Broker -- only CxObj's on Master List contain a description of the application diverts everything down its personal list Filter -- if CxMsg matches some expression, divert TypeFilter- if CxMsg has type in specified set, divert Signal -- signals some task when any CxMsg arrives Sender -- sends copy of CxMsg to some port (asynchronous) Translate- replaces CxMsg with a chain of zero or more new input event CxMsg's Debug -- dumps message contents to debug device (kprintf) Custom -- calls a programmer-provided function (synchronous) There is a more detailed description in the Function Reference sections for the functions which create the various types of CxObj. -- Custom Objects -- Custom objects take a unique action. They call a function provided by the application SYNCHRONOUSLY with the execution of the Commodities handler. The delicacy of this cannot be over- emphasized. The function will execute as part of the input.device task. No DOS or Intuition functions may be called. Although the handoff saves and restores all registers, no assumptions can be made about the values of registers upon entry. For Aztec C functions, it is sufficient (and necessary!) to call the function geta4() (Aztec provided) to establish the context register for the routine. All such functions should be kept quick and simple, with a MINIMUM of stack usage. A Custom CxObj is the only way to directly modify input events as their CxMsg's proceed through the Commodities network, but uses other than that should be thought about long and hard and again. -- Input Events and Matching Conditions -- As mentioned above, most CxMsgs correspond to InputEvents. Now is a good time to reread the Chapter 9, The Input Device, in the ROM Kernel Reference Manual, volume 2. See also the include file devices/inputevent.h. Each input event which reaches the Commodities handler is neatly copied into a CxMsg and sent through the CxObj network. If it makes it all the way through (i.e., to the end of the Master List) the contents--which may have been changed by some object-- are copied into an input event and sent along to subsequent input handlers, including Intuition, and along to Window (i.e., non-Commodities) applications. Flow of an input event CxMsg is determined by its interactions with filter objects. Each filter object has a "matching condition" assigned by the application which determines which messages will be diverted down the filter's personal list (those that match). The internal representation of this matching condition is private, but can be specified by two mechanisms. Enhancements and additions to these mechanisms can be expected; provisions for upward compatibility are made for both. We spend some time going through the currently available capabilities in some detail, since they have avoided documentation elsewhere. -- Input Description Strings -- NOTE: This material is significantly changed for version 0.3 These are the character strings found in the ToolTypes fields described in the introduction to the sample program IHelp. Each string described a subset of input events. [class] [{[-](qual | syn)}] [[-]upstroke] [highmap|ansicode] which means an optional class (default is RAWKEY), zero or more qualifiers, and a mandatory code value, where "class," "qualifier," and "code" in lower case, from the following list: class -- one of the strings: rawkey, rawmouse, event, pointerpos, timer, newprefs, diskremoved, diskinserted. If not specified, the class is taken to be "rawkey." qual -- one of the strings: shift, rshift, capslock, control, lalt, ralt, lcommand, rcommand, numericpad, repeat, midbutton, rbutton, leftbutton, relativemouse, A preceding '-' means that the value of the corresponding qualifier is to be considered irrelevant. syn -- (synonym) one of the strings: shift, caps, alt shift (means "left or right shift"), caps (means "either shift or capslock"), alt (means "either alt key"). upstroke-- (literally "upstroke") if this token is absent, only downstrokes are considered for rawmouse (mousebuttons) and rawkey events. If it is present alone, only upstrokes count. If it preceded by '-' it means that both up and down strokes are included. highmap -- one of the strings: space, backspace, tab, enter, return, esc, del, up, down, right, left, help, f1, f2, f3, f4, f5, f6, f7, f8, f9, f10. ansicode -- a single character token is interpreted as a character code, which is looked up in the system default keymap. Examples of strings are: "lshift right alt f2" "alt shift a" "-shift -alt -control help" (help key with or without qualifiers) "rawmouse rbutton" (mouse move with menu button down) Enhancements to the grammar are anticipated. Every attempt will be made to be compatibile with the input descriptions of the early version. -- Input Expressions -- Applications can also use a powerful binary specification of the matching condition for a filter. In the future, perhaps a more powerful specification may be developed so the data structures for the Input Expressions (type IX) are tagged with their version number. This will allow easy handling of different specification types co-existing in a future Commodities version. The Version 2 IX structure is as follows and the conditions that it specifies a match with an InputEvent are described: typedef struct { UBYTE ix_Version; UBYTE ix_Class; UWORD ix_Code; UWORD ix_CodeMask; UWORD ix_Qualifier; UWORD ix_QualMask; UWORD ix_QualSame; } IX; ix_Version -- must be set to the manifest constant IX_VERSION found in the same include file ("ix.h") as the structure definition. ix_Class -- must exactly equal the ie_Class field of an InputEvent to match. ix_Code, ix_CodeMask -- for every bit set in ix_CodeMask, the state of the corresponding bits in ix_Code and ie_Code in the InputEvent must match. Note that whether a keystroke or mouse button action is a down- or upstroke is encoded in the ie_Code field of the InputEvent (IE_CODE_UPPREFIX). ix_Qualifier, ix_QualMask, ix_QualSame -- the fields ix_QualMask and ix_QualMask work in the same way as for the Code: the Mask indicates the "do care" bits in ie_Qualifier, with ix_Qualifier specifying the required settings for those bits. The ix_QualSame field is used to express simple synonyms in the ie_Qualifier. Using this, you can specify that left- and right Shift- are equivalent and whether the CAPSLOCK qualifier is also equivalent. Left- and right-Alt can also be made equivalent. -- Message Routing -- So far a few points have come out about routing CxMsg's: -In the absence of some action diverting them, after visiting a CxObj, they will proceed to the next node in the same list. -They may be diverted down the "personal list" of some CxObj, normally the list belonging to the object doing the diverting. Diverting consists of pushing the address of the current CxObj onto an internal stack and routing to the first CxObj in the list. -When they reach the end of a list of CxObj's, the address of a CxObj is popped off of their stack, and they proceed to the Successor of that object. Reaching the end of the Master List sends the CxMsg to an internal "Zero Object" which disposes of the message, first recovering InputEvents from the contents of input event messages. Application programs (using Custom Objects) can route a message two ways: diverting it down the list of some object, or by routing it directly to another object. Future functions may be provided for independently pushing or popping the routing stack. Note that it makes no sense and is indicative of greater misunder- standing to try to route a message sent to a port by a sender CxObj. ----- The Examples, Revisited ---------------------------- With the background so far, it is helpful to consider the object structure used by the example programs discussed above. -- IHelp -- IHelp has three "hotkeys." These are triads of objects discussed briefly above. There is a routine in the support library that creates these groups of objects easily. A hotkey triad, to review, consists of a filter object, which is the "trigger" for the hotkey. Attached to its personal list is a sender which sends a notification message to a port allocated by IHelp. The ID field of the several senders differ, so that IHelp can easily tell from which sender the messages were sent. IHelp pays no attention to the data part of the messages it is sent. Following the sender in the personal list of the filter is a translator object which translates the trigger CxMsg to NULL, in effect swallowing it. IHelp, like all good Commodities, has a Broker, and the filter objects at the head of the hotkeys are all attached to its list. -- NoCapsLock -- Attached to the Broker list of this application is a single filter which watches for all RAWKEY events which have the CAPSLOCK bit set. It diverts them down its list where a single custom object can be found. This custom object modifies the InputEvent included in each CxMsg it encounters, clearing the CAPSLOCK bit. It has no effect on other Qualifier bits, so even if the CapsLock key is active, the shift keys will function normally. -- Autopoint2 -- Attached to the Broker is a single filter, watching for RAWMOUSE events with neither mouse button depressed. CxMsgs carrying such events are diverted down to a signal CxObj, which wakes up the AutoPoint task. Once awakened it does magic. Note that a signal is just the ticket for this function, saving the overhead of creating, sending, and replying to an Exec message. ----- More Details ---------------------------------------- -- Error Handling -- A well-behaved program must always check that functions which create CxObj's succeed, since each object requires some dynamically allocated memory. To make this a little less tedious, it is possible to get by testing if entire list of objects was created successfully, and to recover gracefully if not. See the examples. And check for and handle all errors, OK? -- ToolTypes and the Commodities Environment -- Some functions are provided to make it easy to use ToolTypes for providing user control over the parameters of your application. Please let the user specify the input description for major semantic actions in your programs. Also, even if there is no obvious reason in some cases, let the user set the priority for your broker. That is the key step to making the functioning of a group of Commodities applications independent of the order in which they were loaded. Note that the functions provided also support command line argument parsing so Commodities can be started from the CLI with full user control (this is especially useful for starting up a batch of applications from an Execute script file). -- Library version -- Be sure to specify a non-zero version number to the OpenLibrary() call when opening Commodities. This insures that the end user does not use your program with a version of the library that doesn't support new features you are depending on. -- Terminating a Commodities Application -- As is shown in the examples, the proper terminating condition of a Commodities application is the receipt of the Control-E break signal. This signal will be sent by controller software to the task which created a Broker when the user indicates that that Broker's program is to be terminated. It is also easy to send such a signal to a background task started from the CLI. Use the "Status" command to find the tasks CLI ID, and then say "Break task <n> E" where <n> is the number from the Status output. Developing a Commodities application is made more convenient using this convention (we often test them in the foreground, and typing Control-E usually works long before the rest of the program), and we also don't waste function keys or other input combinations on termination commands. -- Pools and Alerts -- The internal data structures used by the Commodities library are allocated and managed by a common "Pool" mechanism. Normally, this mechanism is invisible to the programmer and end-user. It is used to manage data storage for Commodities objects, messages, Exec messages, and InputEvents. In the early releases of Commodities, however, this one included, a recoverable alert will be put up if a program corrupts the secret header of a Commodities data structure, or uses an invalid handle in certain operations. Another recoverable alert is posted when commodities.library expunges (which is done when the last application closes the library) if all data structures are not returned to Commodities before this time. The frequent causes for this are not replying to all the Exec messages Commodities senders send to you, and not deleting all the objects that you have created. To properly reply all Exec messages sent to your program, a sequence like that used in IHelp is advised: DeleteCxObjAll(broker); while (msg = GetMsg(port)) ReplyMsg(msg); CloseLibrary(CxBase); ----- Future Versions and Compatibility ------------------- As stated in the Preface, this version of Commodities Exchange is not complete, with a few important things not present. In this section we discuss things to come and compatibility issues. -- Controller -- Prominent in its absence is the controller application that will allow the user to view (the brokers of) all the Commodities applications, experiment with their priority, temporarily disable them, and terminate them. It was a design goal to provide enough procedural interface through the library to allow a "legal" application to walk through the Commodities object tree and report what it sees, but implementation of that interfered with the main functions of the library. Until at least a rudimentary controller is made available, Commodities applications are best started from the CLI, so that they may be terminated by the CLI "Break" command (using the Control-E signal). Note that the "ToolTypes" parameter environment can be specified on the CLI command line, like so: run ihelp "CYCLEBACK=alt shift f5" -- User Visible Filters -- Another dream for the controller is that it could report on some of the hotkeys or other event triggers that an application had installed. This would provide, for example, an easy way for the user to see exactly what key cycles the windows in IHelp. To accomplish this, an extension will need to be made of the Filter, with the application further specifying descriptive text for user-visible filters, and whether the user may modify the event matching condition, and what restrictions apply to his modifications. Prototypes of this have been played with, but the inclusion into the library will have to wait. Existing filters will always be compatible, but even those that should be visible to the user never will be. -- Active Window Knowledge -- It is in the plans to hang another Commodities input handler on the input.device handler chain, but FOLLOWING Intuition instead of preceeding (but preceding the Console). This would allow a keystroke enhancer to make different translations for different windows. Another use of such a thing would be to allow non-interactive programs (i.e., those with no window) be informed of a preferences change. This will manifest itself as a new flag bit that can be set in the NewBroker structure to indicate post-Intuition processing, and a new kind of filter which only diverts events if a particular window is active. Religiously setting all undefined NewBroker.nb_Flags bits to zero will insure compatibility with this change. -- BindCommodities -- In spite of the lack of a controller today, the preferred method of starting a Commodities application and establishing a parameter environment will be through the use of icons. In the meantime, one can start up several Commodities applications with a batch file (which can't be run from the start-up script since jobs left in the background prevent the Initial CLI from closing). When we make it to icons, we will need a way to start up a collection of Commodities by referencing their icons. Neil "Workbench" Katin, author also of BindDrivers, pledges a similar program which will start every program with an icon in some specified drawer, with their start-up environment being identical to that when started from the Workbench. Such a program will have myriad uses (starting notepads, etc.) but our interest will be in starting a directory full of Commodities applications. -- Timer Support -- Right now, events of type IECLASS_TIMER don't go through the Commodities object network, largely because there wasn't time to profile the performance of the system, and they are a frequent and low-payoff burden. A new standard object, the "One-Shot Timer Filter," will someday exist, which will be set to some unsigned integer value by the application. Each time a TIMER event passes its way, it will decrement the count. When the count reaches zero, ONE timer CxMsg will be diverted down the filter's personal list, and the filter will then become dormant until the count is reset. -- Profile and Downcode -- We don't know how slow this beast is, especially with lots and lots of objects. Existing profilers don't apply to Exec library code, and there hasn't been any time to do something about it. With the timers eliminated, the author's experience hacking Intuition indicates that human-schedule input is pretty slow, and that any input-response bottleneck typically occur on the output side of the fence. That is to say, we hope it's fast enough. There are several routines which are prime contestants for assembly language downcoding. If there is sufficient uproar, we will break apart the library interface functions of the scanned library into separate files, so that your program will only link in just the interface code it needs. -- Keystroke Programmers -- Although lots of features are present to make writing a keystroke macro utility much easier, reports of direct experience returned to the author will undoubtedly show areas of needed change. We will try to be most responsive to people forging new ground. -- More CxMsg Types -- There are only two types of Commodities Messages currently: CXM_IEVENT, by far the most common; and CXM_UNIQUE, which notifies Brokers who are interested that another attempt was made to start their applications. More may be coming, perhaps in support of Post-Intuition Commodities. Program defensively by not assuming anything about the type of a CxMsg unless that message has passed through a filter of some sort. -- Support for More Languages -- Commodities Exchange was developed under Aztec-C, and the scanned library cx_support.lib is an Aztec convention, small model library. Amiga type naming, as found in exec/types.h, are used exclusively in commodities.library, but some 'ints' sneaked into cx_support.lib. Support for other compilers, languages, and assembler should be done someday. Particularly lacking are assembler include files. -- Documentation -- Hopefully, the state of this manual will succumb to revision. APPENDIX (for now) Three big changes have been added: The function InvertKeyMap() converts an ANSI character code to the InputEvent that maps to it (using KeyMaps). This function is used by the function InvertString() which translates a special extension of ANSI character strings into a chain of input events. ParseIX() has been greatly enhances (and tested a little). See the description above, in this document. AddIEvents() provides a trivial method of adding a chain of input events to the Input Food Chain starting before Commodities. See the function descriptions for more information.